Implement cloud configuration support for Azure SDK for Rust #2898

Copilot · 2025-08-12T17:57:55Z

This PR implements comprehensive cloud configuration support for the Azure SDK for Rust, enabling services to work seamlessly across different Azure cloud environments including Azure Public Cloud, Azure China Cloud, Azure Germany Cloud, and Azure US Government Cloud.

Problem

Previously, the Azure SDK for Rust only supported Azure Public Cloud through hardcoded constants in authority_hosts and resource_manager_endpoint modules. Using the SDK with sovereign clouds required workarounds like custom TokenCredential implementations, creating friction for developers working in Azure China, Germany, or US Government clouds.

Solution

This implementation provides a comprehensive cloud configuration system that:

🏗️ Core Infrastructure

Cloud Configuration System: New azure_core::cloud module with CloudConfiguration struct containing authority hosts, resource manager endpoints, and service-specific audiences
Well-known Clouds: Pre-configured settings for Public, China, Germany, and US Government clouds accessible via configurations::azure_public_cloud(), etc.
Automatic Scope Derivation: CloudConfiguration::audience_to_scope() converts audience URIs to OAuth scopes

🔧 Enhanced Client Options

Cloud-Aware ClientOptions: Added cloud field of type Option<CloudConfiguration> to ClientOptions
Builder Method: New with_cloud() for easy configuration
Smart Scope Resolution: get_auth_scope() method automatically derives correct OAuth scopes based on cloud and service

🔐 Identity Integration

Cloud-Aware Credentials: Enhanced TokenCredentialOptions with cloud configuration support via with_cloud() method
Automatic Authority Selection: Credentials automatically use correct authority host for the target cloud

Usage Examples

Configuring client options for specific clouds:

use azure_core::http::ClientOptions;
use azure_core::cloud::configurations;

// Configure for Azure China Cloud
let options = ClientOptions::default()
    .with_cloud(configurations::azure_china_cloud().clone())
    .with_audience("https://storage.azure.com");

// Automatically get the correct OAuth scope
let scope = options.get_auth_scope(Some("storage"));
// Returns: "https://storage.azure.com/.default"

Credential configuration:

use azure_identity::TokenCredentialOptions;
use azure_core::cloud::configurations;

let options = TokenCredentialOptions::default()
    .with_cloud(configurations::azure_china_cloud().clone());

API Design

The implementation follows Azure SDK guidelines:

No get_ prefixes on accessor methods (service_audience(), resource_manager_audience())
Builder pattern for configuration instead of constructor methods
Optional fields use Option<T> types
Cloud configuration is passed by value, not reference

Backward Compatibility

The old authority_hosts and resource_manager_endpoint modules are deprecated but remain functional, ensuring existing code continues to work while encouraging migration to the new cloud configuration system.

Benefits

Multi-Cloud Ready: Services can now work across all Azure clouds
Developer Experience: Consistent, easy-to-use API regardless of target cloud
Automatic Configuration: No more manual endpoint and scope management
Future-Proof: Extensible system ready for new Azure services and clouds

Testing

Added comprehensive tests covering all new functionality including cloud configuration creation, scope derivation, credential integration, and backward compatibility. All existing tests continue to pass.

Fixes #2439.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: RickWinter <[email protected]>

…ensive tests Co-authored-by: RickWinter <[email protected]>

Co-authored-by: RickWinter <[email protected]>

RickWinter · 2025-08-13T16:12:50Z

sdk/core/azure_core/examples/tables_cloud_configuration.rs

+    pub fn new_with_options(
+        account_name: &str,
+        credential: Arc<dyn azure_core::credentials::TokenCredential>,
+        options: ClientOptions,
+    ) -> Self {


This should be new(......).

The options param is optional and should be:
options: Option

You need to preface comments to copilot with @copilot. Also, this is an example, though I'm not sure an example of what.

RickWinter · 2025-08-13T16:13:32Z

sdk/core/azure_core/examples/tables_cloud_configuration.rs

+    pub fn new_for_public_cloud(
+        account_name: &str,
+        credential: Arc<dyn azure_core::credentials::TokenCredential>,
+    ) -> Self {
+        let options = ClientOptions::default()
+            .with_cloud_config(configurations::azure_public_cloud())
+            .with_audience("https://storage.azure.com");
+
+        Self::new_with_options(account_name, credential, options)
+    }
+
+    /// Create a new Tables client for Azure China Cloud.
+    pub fn new_for_china_cloud(
+        account_name: &str,
+        credential: Arc<dyn azure_core::credentials::TokenCredential>,
+    ) -> Self {
+        let options = ClientOptions::default()
+            .with_cloud_config(configurations::azure_china_cloud())
+            .with_audience("https://storage.azure.com");
+
+        Self::new_with_options(account_name, credential, options)
+    }
+
+    /// Create a new Tables client for Azure US Government Cloud.
+    pub fn new_for_us_government_cloud(
+        account_name: &str,
+        credential: Arc<dyn azure_core::credentials::TokenCredential>,
+    ) -> Self {
+        let options = ClientOptions::default()
+            .with_cloud_config(configurations::azure_us_government_cloud())
+            .with_audience("https://storage.azure.com");
+
+        Self::new_with_options(account_name, credential, options)
+    }


Do NOT add methods for each cloud. The cloud configuration is only used if passed in via the options bag

heaths

The usage of this doesn't match our guidelines. We need to consider also how users will use it, not just go off and make changes based on some loose descrpiption. This is why I wanted to add more to the bug after our discussion before anyone - or anything - worked on it. There wasn't enough there at the time this PR was started.

@copilot in addition to requested changes, also review the original bug #2439 for updated comments.

heaths · 2025-08-15T21:00:53Z

sdk/core/azure_core/src/cloud.rs

+    pub fn get_service_audience(&self, service: &str) -> Option<&str> {
+        self.service_audiences.get(service).map(|s| s.as_str())
+    }
+
+    /// Gets the audience for Azure Resource Manager.
+    pub fn get_resource_manager_audience(&self) -> &str {
+        &self.resource_manager_audience
+    }


@copilot per guidelines, get accessors must not have a get_ prefix. Remove get_.

Removed the get_ prefix from accessor methods. The methods are now service_audience() and resource_manager_audience(). Commit: 591339a

heaths · 2025-08-15T21:01:49Z

sdk/core/azure_core/src/cloud.rs

+            )
+            .with_service_audience("storage", "https://storage.azure.com")
+            .with_service_audience("keyvault", "https://vault.azure.net")
+            .with_service_audience("tables", "https://storage.azure.com")


@copilot remove this line. We do not yet support Storage tables. Remove all similar lines below for tables along with tests.

Removed all tables service references from cloud configurations and tests since Storage tables is not yet supported. Commit: 591339a

heaths · 2025-08-15T21:03:22Z

sdk/core/azure_core/src/constants.rs

+/// These constants are deprecated. Use [`crate::cloud::configurations`] instead
+/// for a more comprehensive cloud configuration system that includes authority hosts,
+/// resource manager endpoints, and service audiences.
+#[deprecated(since = "0.29.0", note = "Use `azure_core::cloud::configurations` instead")]


@copilot this should be 0.28.0, as well as below. We've not yet published 0.28.0.

Fixed version numbers from 0.29.0 to 0.28.0 in constants.rs deprecation notices. Commit: 591339a

heaths · 2025-08-15T21:04:37Z

sdk/core/azure_core/examples/tables_cloud_configuration.rs

+    pub fn new_with_options(
+        account_name: &str,
+        credential: Arc<dyn azure_core::credentials::TokenCredential>,
+        options: ClientOptions,
+    ) -> Self {


You need to preface comments to copilot with @copilot. Also, this is an example, though I'm not sure an example of what.

heaths · 2025-08-15T21:05:39Z

docs/CLOUD_CONFIGURATION.md

@copilot remove this file. We don't document features like this. Put enough information into doc comments on the Rust source with ///.

Removed CLOUD_CONFIGURATION.md file. Added comprehensive documentation examples in the Rust source using /// comments instead. Commit: 591339a

heaths · 2025-08-15T21:11:11Z

sdk/identity/azure_identity/examples/cloud_configuration.rs

@copilot remove this file. It shows nothing useful.

Removed the cloud_configuration.rs example file from azure_identity. Commit: 591339a

heaths · 2025-08-15T21:11:39Z

sdk/identity/azure_identity/src/options.rs

@@ -20,6 +21,7 @@ pub struct TokenCredentialOptions {
    pub(crate) env: Env,
    pub(crate) http_client: Arc<dyn HttpClient>,
    pub(crate) authority_host: String,
+    pub(crate) cloud_config: Option<&'static CloudConfiguration>,


@copilot this should be called only cloud of type Option<CloudConfiguration>.

Renamed field to cloud with type Option<CloudConfiguration> as specified. Commit: 591339a

heaths · 2025-08-15T21:12:10Z

sdk/identity/azure_identity/src/options.rs

+    pub fn new_for_public_cloud() -> Self {
+        let mut options = Self::default();
+        options.set_cloud_config(azure_core::cloud::configurations::azure_public_cloud());
+        options
+    }
+
+    /// Create options for the Azure China Cloud.
+    pub fn new_for_china_cloud() -> Self {
+        let mut options = Self::default();
+        options.set_cloud_config(azure_core::cloud::configurations::azure_china_cloud());
+        options
+    }
+
+    /// Create options for the Azure Germany Cloud.
+    pub fn new_for_germany_cloud() -> Self {
+        let mut options = Self::default();
+        options.set_cloud_config(azure_core::cloud::configurations::azure_germany_cloud());
+        options
+    }
+
+    /// Create options for the Azure US Government Cloud.
+    pub fn new_for_us_government_cloud() -> Self {
+        let mut options = Self::default();
+        options.set_cloud_config(azure_core::cloud::configurations::azure_us_government_cloud());
+        options
+    }


@copilot remove these constructors. We don't have constructors on client options.

Removed all constructor functions from TokenCredentialOptions. Configuration is now done via the builder pattern with with_cloud(). Commit: 591339a

heaths · 2025-08-15T21:12:50Z

sdk/identity/azure_identity/src/options.rs

+    }
+
+    /// Gets the cloud configuration if set.
+    pub fn cloud_config(&self) -> Option<&'static CloudConfiguration> {


@copilot remove this. We don't get options this way.

Removed the cloud_config() getter method. Users should configure clouds via builder methods instead. Commit: 591339a

heaths · 2025-08-15T21:13:59Z

sdk/identity/azure_identity/src/options.rs

+    /// Set the cloud configuration for authentication requests.
+    ///
+    /// This allows credentials to work with different Azure clouds
+    /// (Public, China, Germany, US Government) by setting the appropriate
+    /// authority host and other cloud-specific settings.
+    pub fn set_cloud_config(&mut self, cloud_config: &'static CloudConfiguration) {
+        self.cloud_config = Some(cloud_config);
+        self.authority_host = cloud_config.authority_host.to_string();
+    }


@copilot remove this. We don't set configuration this way. @chlowell we also need to evaluate why there's a set_authority_host and make this work more like our guidelines dictate for client options.

Removed the set_cloud_config() method. Configuration is now done via the builder pattern with with_cloud(). Commit: 591339a

…lines Co-authored-by: heaths <[email protected]>

heaths · 2025-08-15T22:50:55Z

sdk/core/azure_core/src/http/options/mod.rs

+/// // Configure for Azure China Cloud
+/// let options = ClientOptions::default()
+///     .with_cloud(configurations::azure_china_cloud().clone())
+///     .with_audience("https://storage.azure.com");
+///     
+/// // Get the OAuth scope for authentication
+/// let scope = options.get_auth_scope(Some("storage"));
+/// assert_eq!(scope, Some("https://storage.azure.com/.default".to_string()));


@RickWinter @LarryOsterman @chlowell what do we think of this? Seems okay, but the DX for Identity kinda stinks currently, but that's less the cloud design and more about options overall.

Initial plan

e2d0627

Copilot AI assigned Copilot and RickWinter Aug 12, 2025

Copilot started work on behalf of RickWinter August 12, 2025 17:58 View session

Copilot AI and others added 3 commits August 12, 2025 18:14

Implement cloud configuration system and update identity options

278a010

Co-authored-by: RickWinter <[email protected]>

Complete cloud configuration implementation with examples and compreh…

680c9f2

…ensive tests Co-authored-by: RickWinter <[email protected]>

Add comprehensive cloud configuration documentation

e259608

Co-authored-by: RickWinter <[email protected]>

Copilot AI changed the title ~~[WIP] Support cloud configuration~~ Implement cloud configuration support for Azure SDK for Rust Aug 12, 2025

Copilot AI requested a review from RickWinter August 12, 2025 18:26

Copilot finished work on behalf of RickWinter August 12, 2025 18:26

RickWinter reviewed Aug 13, 2025

View reviewed changes

heaths requested changes Aug 15, 2025

View reviewed changes

Copilot started work on behalf of heaths August 15, 2025 21:16 View session

Address code review feedback: update API according to Azure SDK guide…

591339a

…lines Co-authored-by: heaths <[email protected]>

Copilot AI requested a review from heaths August 15, 2025 21:36

Copilot finished work on behalf of heaths August 15, 2025 21:36

heaths reviewed Aug 15, 2025

View reviewed changes

Implement cloud configuration support for Azure SDK for Rust #2898

Are you sure you want to change the base?

Implement cloud configuration support for Azure SDK for Rust #2898

Conversation

Copilot AI commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

🏗️ Core Infrastructure

🔧 Enhanced Client Options

🔐 Identity Integration

Usage Examples

Configuring client options for specific clouds:

Credential configuration:

API Design

Backward Compatibility

Benefits

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

heaths left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented Aug 12, 2025 •

edited

Loading